home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / io / DataOutput.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  13.0 KB  |  341 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)DataOutput.java    1.10 98/06/29
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17. /**
  18.  * The <code>DataOutput</code> interface provides
  19.  * for converting data from any of the Java
  20.  * primitive types to a series of bytes and
  21.  * writing these bytes to a binary stream.
  22.  * There is  also a facility for converting
  23.  * a <code>String</code> into Java modified
  24.  * UTF-8 format and writing the resulting series
  25.  * of bytes.
  26.  * <p>
  27.  * For all the methods in this interface that
  28.  * write bytes, it is generally true that if
  29.  * a byte cannot be written for any reason,
  30.  * an <code>IOException</code> is thrown.
  31.  *
  32.  * @author  Frank Yellin
  33.  * @version 1.10, 06/29/98
  34.  * @see     java.io.DataInput
  35.  * @see     java.io.DataOutputStream
  36.  * @since   JDK1.0
  37.  */
  38. public
  39. interface DataOutput {
  40.     /**
  41.      * Writes to the output stream the eight
  42.      * low-order bits of the argument <code>b</code>.
  43.      * The 24 high-order  bits of <code>b</code>
  44.      * are ignored.
  45.      *
  46.      * @param      b   the byte to be written.
  47.      * @exception  IOException  if an I/O error occurs.
  48.      */
  49.     void write(int b) throws IOException;
  50.  
  51.     /**
  52.      * Writes to the output stream all the bytes in array <code>b</code>.
  53.      * If <code>b</code> is <code>null</code>,
  54.      * a <code>NullPointerException</code> is thrown.
  55.      * If <code>b.length</code> is zero, then
  56.      * no bytes are written. Otherwise, the byte
  57.      * <code>b[0]</code> is written first, then
  58.      * <code>b[1]</code>, and so on; the last byte
  59.      * written is <code>b[b.length-1]</code>.
  60.      *
  61.      * @param      b   the data.
  62.      * @exception  IOException  if an I/O error occurs.
  63.      */
  64.     void write(byte b[]) throws IOException;
  65.  
  66.     /**
  67.      * Writes <code>len</code> bytes from array
  68.      * <code>b</code>, in order,  to
  69.      * the output stream.  If <code>b</code>
  70.      * is <code>null</code>, a <code>NullPointerException</code>
  71.      * is thrown.  If <code>off</code> is negative,
  72.      * or <code>len</code> is negative, or <code>off+len</code>
  73.      * is greater than the length of the array
  74.      * <code>b</code>, then an <code>IndexOutOfBoundsException</code>
  75.      * is thrown.  If <code>len</code> is zero,
  76.      * then no bytes are written. Otherwise, the
  77.      * byte <code>b[off]</code> is written first,
  78.      * then <code>b[off+1]</code>, and so on; the
  79.      * last byte written is <code>b[off+len-1]</code>.
  80.      *
  81.      * @param      b     the data.
  82.      * @param      off   the start offset in the data.
  83.      * @param      len   the number of bytes to write.
  84.      * @exception  IOException  if an I/O error occurs.
  85.      */
  86.     void write(byte b[], int off, int len) throws IOException;
  87.  
  88.     /**
  89.      * Writes a <code>boolean</code> value to this output stream.
  90.      * If the argument <code>v</code>
  91.      * is <code>true</code>, the value <code>(byte)1</code>
  92.      * is written; if <code>v</code> is <code>false</code>,
  93.      * the  value <code>(byte)0</code> is written.
  94.      * The byte written by this method may
  95.      * be read by the <code>readBoolean</code>
  96.      * method of interface <code>DataInput</code>,
  97.      * which will then return a <code>boolean</code>
  98.      * equal to <code>v</code>.
  99.      *
  100.      * @param      v   the boolean to be written.
  101.      * @exception  IOException  if an I/O error occurs.
  102.      */
  103.     void writeBoolean(boolean v) throws IOException;
  104.  
  105.     /**
  106.      * Writes to the output stream the eight low-
  107.      * order bits of the argument <code>v</code>.
  108.      * The 24 high-order bits of <code>v</code>
  109.      * are ignored. (This means  that <code>writeByte</code>
  110.      * does exactly the same thing as <code>write</code>
  111.      * for an integer argument.) The byte written
  112.      * by this method may be read by the <code>readByte</code>
  113.      * method of interface <code>DataInput</code>,
  114.      * which will then return a <code>byte</code>
  115.      * equal to <code>(byte)v</code>.
  116.      *
  117.      * @param      v   the byte value to be written.
  118.      * @exception  IOException  if an I/O error occurs.
  119.      */
  120.     void writeByte(int v) throws IOException;
  121.  
  122.     /**
  123.      * Writes two bytes to the output
  124.      * stream to represent the value of the argument.
  125.      * The byte values to be written, in the  order
  126.      * shown, are: <p>
  127.      * <pre><code>
  128.      * (byte)(0xff & (v >> 8))
  129.      * (byte)(0xff & v)
  130.      * </code> </pre> <p>
  131.      * The bytes written by this method may be
  132.      * read by the <code>readShort</code> method
  133.      * of interface <code>DataInput</code> , which
  134.      * will then return a <code>short</code> equal
  135.      * to <code>(short)v</code>.
  136.      *
  137.      * @param      v   the <code>short</code> value to be written.
  138.      * @exception  IOException  if an I/O error occurs.
  139.      */
  140.     void writeShort(int v) throws IOException;
  141.  
  142.     /**
  143.      * Writes a <code>char</code> value, wich
  144.      * is comprised of two bytes, to the
  145.      * output stream.
  146.      * The byte values to be written, in the  order
  147.      * shown, are:
  148.      * <p><pre><code>
  149.      * (byte)(0xff & (v >> 8))
  150.      * (byte)(0xff & v)
  151.      * </code></pre><p>
  152.      * The bytes written by this method may be
  153.      * read by the <code>readChar</code> method
  154.      * of interface <code>DataInput</code> , which
  155.      * will then return a <code>char</code> equal
  156.      * to <code>(char)v</code>.
  157.      *
  158.      * @param      v   the <code>char</code> value to be written.
  159.      * @exception  IOException  if an I/O error occurs.
  160.      */
  161.     void writeChar(int v) throws IOException;
  162.  
  163.     /**
  164.      * Writes an <code>int</code> value, which is
  165.      * comprised of four bytes, to the output stream.
  166.      * The byte values to be written, in the  order
  167.      * shown, are:
  168.      * <p><pre><code>
  169.      * (byte)(0xff & (v >> 24))
  170.      * (byte)(0xff & (v >> 16))
  171.      * (byte)(0xff & (v >>    8))
  172.      * (byte)(0xff & v)
  173.      * </code></pre><p>
  174.      * The bytes written by this method may be read
  175.      * by the <code>readInt</code> method of interface
  176.      * <code>DataInput</code> , which will then
  177.      * return an <code>int</code> equal to <code>v</code>.
  178.      *
  179.      * @param      v   the <code>int</code> value to be written.
  180.      * @exception  IOException  if an I/O error occurs.
  181.      */
  182.     void writeInt(int v) throws IOException;
  183.  
  184.     /**
  185.      * Writes an <code>long</code> value, which is
  186.      * comprised of four bytes, to the output stream.
  187.      * The byte values to be written, in the  order
  188.      * shown, are:
  189.      * <p><pre><code>
  190.      * (byte)(0xff & (v >> 48))
  191.      * (byte)(0xff & (v >> 40))
  192.      * (byte)(0xff & (v >> 32))
  193.      * (byte)(0xff & (v >> 24))
  194.      * (byte)(0xff & (v >> 16))
  195.      * (byte)(0xff & (v >>  8))
  196.      * (byte)(0xff & v)
  197.      * </code></pre><p>
  198.      * The bytes written by this method may be
  199.      * read by the <code>readLong</code> method
  200.      * of interface <code>DataInput</code> , which
  201.      * will then return a <code>long</code> equal
  202.      * to <code>v</code>.
  203.      *
  204.      * @param      v   the <code>long</code> value to be written.
  205.      * @exception  IOException  if an I/O error occurs.
  206.      */
  207.     void writeLong(long v) throws IOException;
  208.  
  209.     /**
  210.      * Writes a <code>float</code> value,
  211.      * which is comprised of four bytes, to the output stream.
  212.      * It does this as if it first converts this
  213.      * <code>float</code> value to an <code>int</code>
  214.      * in exactly the manner of the <code>Float.floatToIntBits</code>
  215.      * method  and then writes the <code>int</code>
  216.      * value in exactly the manner of the  <code>writeInt</code>
  217.      * method.  The bytes written by this method
  218.      * may be read by the <code>readFloat</code>
  219.      * method of interface <code>DataInput</code>,
  220.      * which will then return a <code>float</code>
  221.      * equal to <code>v</code>.
  222.      *
  223.      * @param      v   the <code>float</code> value to be written.
  224.      * @exception  IOException  if an I/O error occurs.
  225.      */
  226.     void writeFloat(float v) throws IOException;
  227.  
  228.     /**
  229.      * Writes a <code>double</code> value,
  230.      * which is comprised of eight bytes, to the output stream.
  231.      * It does this as if it first converts this
  232.      * <code>double</code> value to a <code>long</code>
  233.      * in exactly the manner of the <code>Double.doubleToLongBits</code>
  234.      * method  and then writes the <code>long</code>
  235.      * value in exactly the manner of the  <code>writeLong</code>
  236.      * method. The bytes written by this method
  237.      * may be read by the <code>readDouble</code>
  238.      * method of interface <code>DataInput</code>,
  239.      * which will then return a <code>double</code>
  240.      * equal to <code>v</code>.
  241.      *
  242.      * @param      v   the <code>double</code> value to be written.
  243.      * @exception  IOException  if an I/O error occurs.
  244.      */
  245.     void writeDouble(double v) throws IOException;
  246.  
  247.     /**
  248.      * Writes a string to the output stream.
  249.      * For every character in the string
  250.      * <code>s</code>,  taken in order, one byte
  251.      * is written to the output stream.  If
  252.      * <code>s</code> is <code>null</code>, a <code>NullPointerException</code>
  253.      * is thrown.<p>  If <code>s.length</code>
  254.      * is zero, then no bytes are written. Otherwise,
  255.      * the character <code>s[0]</code> is written
  256.      * first, then <code>s[1]</code>, and so on;
  257.      * the last character written is <code>s[s.length-1]</code>.
  258.      * For each character, one byte is written,
  259.      * the low-order byte, in exactly the manner
  260.      * of the <code>writeByte</code> method . The
  261.      * high-order eight bits of each character
  262.      * in the string are ignored.
  263.      *
  264.      * @param      s   the string of bytes to be written.
  265.      * @exception  IOException  if an I/O error occurs.
  266.      */
  267.     void writeBytes(String s) throws IOException;
  268.  
  269.     /**
  270.      * Writes every character in the string <code>s</code>,
  271.      * to the output stream, in order,
  272.      * two bytes per character. If <code>s</code>
  273.      * is <code>null</code>, a <code>NullPointerException</code>
  274.      * is thrown.  If <code>s.length</code>
  275.      * is zero, then no characters are written.
  276.      * Otherwise, the character <code>s[0]</code>
  277.      * is written first, then <code>s[1]</code>,
  278.      * and so on; the last character written is
  279.      * <code>s[s.length-1]</code>. For each character,
  280.      * two bytes are actually written, high-order
  281.      * byte first, in exactly the manner of the
  282.      * <code>writeChar</code> method.
  283.      *
  284.      * @param      s   the string value to be written.
  285.      * @exception  IOException  if an I/O error occurs.
  286.      */
  287.     void writeChars(String s) throws IOException;
  288.  
  289.     /**
  290.      * Writes two bytes of length information
  291.      * to the output stream, followed
  292.      * by the Java modified UTF representation
  293.      * of  every character in the string <code>s</code>.
  294.      * If <code>s</code> is <code>null</code>,
  295.      * a <code>NullPointerException</code> is thrown.
  296.      * Each character in the string <code>s</code>
  297.      * is converted to a group of one, two, or
  298.      * three bytes, depending on the value of the
  299.      * character.<p>
  300.      * If a character <code>c</code>
  301.      * is in the range <code>\u0001</code> through
  302.      * <code>\u007f</code>, it is represented
  303.      * by one byte:<p>
  304.      * <pre>(byte)c </pre>  <p>
  305.      * If a character <code>c</code> is <code>\u0000</code>
  306.      * or is in the range <code>\u0080</code>
  307.      * through <code>\u07ff</code>, then it is
  308.      * represented by two bytes, to be written
  309.      * in the order shown:<p> <pre><code>
  310.      * (byte)(0xc0 | (0x1f & (c >> 6)))
  311.      * (byte)(0x80 | (0x3f & c))
  312.      *  </code></pre>  <p> If a character
  313.      * <code>c</code> is in the range <code>\u0800</code>
  314.      * through <code>uffff</code>, then it is
  315.      * represented by three bytes, to be written
  316.      * in the order shown:<p> <pre><code>
  317.      * (byte)(0xc0 | (0x0f & (c >> 12)))
  318.      * (byte)(0x80 | (0x3f & (c >>  6)))
  319.      * (byte)(0x80 | (0x3f & c))
  320.      *  </code></pre>  <p> First,
  321.      * the total number of bytes needed to represent
  322.      * all the characters of <code>s</code> is
  323.      * calculated. If this number is larger than
  324.      * <code>65535</code>, then a <code>UTFDataFormatError</code>
  325.      * is thrown. Otherwise, this length is written
  326.      * to the output stream in exactly the manner
  327.      * of the <code>writeShort</code> method;
  328.      * after this, the one-, two-, or three-byte
  329.      * representation of each character in the
  330.      * string <code>s</code> is written.<p>  The
  331.      * bytes written by this method may be read
  332.      * by the <code>readUTF</code> method of interface
  333.      * <code>DataInput</code> , which will then
  334.      * return a <code>String</code> equal to <code>s</code>.
  335.      *
  336.      * @param      str   the string value to be written.
  337.      * @exception  IOException  if an I/O error occurs.
  338.      */
  339.     void writeUTF(String str) throws IOException;
  340. }
  341.